Use the information in this guide to set the directory services database (AD) and application protocol (LDAP) for the Itential Automation Platform (IAP). Information for configuring OpenLDAP is also provided.
Authentication
The following shows the overall authentication flow in IAP using LDAP.
User provides username and password.
LDAP server in AAA platform authenticates users and returns one of the following:
Reject
: IAP displays "Invalid credentials."Access-Accept
: IAP allows user to login.Challenge
: IAP displays "Generate token and retry."
AAA Platform also returns a vendor specific attribute ( Type 2 per RFC 2865, 5.6). For example:
Vendor ID
= 47688 (Itential)Name
= Itential-user-GroupNumber
= 1Value
= User group of the user obtained from LDAP.
Authorization
The following example illustrates the authorization and authentication flow between IAP and NSO.
User groups will be defined manually in IAP. Matching user groups will be added in the LDAP server in the AAA Platform. Customer must have user groups configured on the LDAP server.
LDAP server will authentication the user.
LDAP server will authorize the user.
Return the groups associated with the user.
User receives the authentication token.
IAP sends a request to NSO with user and token.
Multi-Tenancy
The following steps apply when using multi-tenancy:
NSO sends a
whoami
API request to IAP.IAP returns the group to NSO.
NSO checks the NACM rules for the user/group to determine what the user can access.
NSO will either accept or reject access.
Note: Multi-tenancy is not required for most implementations.
Prerequisites
The LDAP adapter is configured to establish connection with Active Directory and OpenLDAP servers.
For an LDAP based system it becomes important to understand which groups a user belongs to when working on the user information. This is especially important in systems that implement RBAC because understanding the groups for a user is necessary for the authorization process. Fortunately, LDAP has support for reverse membership mapping if the user and group objects use certain object classes. By default, an OpenLDAP system uses the memberOf
overlay; however, this default can be overridden by the userMembershipAttribute
property.
Enable MemberOf Module
If using LDAP in a VM or bare-metal (not a container) environment, you must include the memberof
module in your LDAP config file, otherwise admin permissions will not be granted in IAP. In order for this to take effect in prior releases of Itential, every group created prior to enabling this module must be deleted and remade.
sudo ldapdelete -c -D dc=example,dc=com -w <password> -H ldap:/// -f <ldif_file>
Be sure to include just the DN for each group you want to remove inside the LDIF file.
dn: cn=pronghorn_admin,ou=groups,dc=example,dc=com
Then re-add the groups using the following command:
sudo ldapadd -c -D dc=example,dc=com -w <password> -H ldap:/// -f <ldif_file>
Define LDAP Groups
The groups that will be associated with various IAP applications must be defined in the authentication server.
- SystemAdmin
- DSOperator
- DSManager
- DSEngineer
- Developer
Below is an example of defined groups.
Create LDAP User for IAP
An LDAP user must be set up in the authentication database for IAP to use to connect to the LDAP server to run queries. This user does not need to be a member of any of the defined groups; user simply needs to be able to access the LDAP server.
Confirm Connection to LDAP Server
Before proceeding, verify the LDAP user can connect to the LDAP server. In addition to verifying the ability to connect to the LDAP server, this will provide multiple values needed later in this setup procedure.
This verification can be performed using the following command line tool, which needs to be installed on the IAP server. Once the tool has been installed, execute the following two commands.
Command
export LDAPTLS_REQCERT=never
- The purpose of this command is to force the connection to not use a certification key.
- Run this command only once per SSH session.
- Run this command only if you are connecting via SSL. It is best practice to do this.
Command
ldapsearch -H ldaps://<IP Address of LDAP Server>:<Port> -b '<Base DN>' -D <UserName>@<Domain> -w '<Password>' cn='<Common Name>' -s sub -x
- IP Address of LDAP Server: This will be the IP of your LDAP server. This will be provided by an AD administrator.
- Port: This is the port of the LDAP server. 636 is the standard for SSL connections. 389 is the standard port for non SSL connections.
- Base DN: This is provided by an AD administrator.
- UserName: This is the username that was created for IAP to connect to AD.
- Domain: This is provided by an AD administrator.
- Password: Password for IAP user.
- Common Name: This is provided by an AD administrator.
Below is an example of a successful ldapsearch
connection.
Install LDAP Adapter
Use the following to add adapter-ldap
to your IAP build and to deploy the new build.
The LDAP and Local-AAA adapters can both be installed at the same time. However, only one adapter may be active at any given time.
Utilize multiple properties files for transferring between adapters (recommended best practice).
- The example below shows three properties files are being utilized. One is a connection to the AAA authentication. The second is to the production LDAP server. The third is to the staging LDAP server.
- To change the connection method, copy the correct properties file over the
properties.json
and restart IAP. - This is only required if you expect you will need to change between authentication methods.
Install Root Certificate
The authentication server administrator must provide a certificate for IAP to use.
- Copy this certificate to
/opt/pronghorn/current/custom/keys
.- This will ensure the keys are copied over during an IAP upgrade.
- You may need to create the directory keys.
- Verify the permissions are set to 644.
Configure Properties File
Modify the IAP properties.json
file to incorporate the new LDAP connection.
Create a backup of the configuration file.
Add the values to the configuration files. These values are from the previous
ldapsearch
command and in the groups created in IAP.{ "id": "Prod LDAP", "type": "LDAP", "properties": { "domain": "<Domain>", "url": "ldaps://<IP Address>:<Port>", "bindUsername": "<User>@<Domain>", "bindPassword": "<your_password>", "baseDN": "<Base DN>", "groupSearchFilter": "", "userSearchFilter": "sAMAccountName", "timeout": 5000, "healthCheckInterval": 5000, "connectTimeout": 5000, "idleTimeout": 5000, "timeLimit": 10, "reconnect": true, "activeDirectory": true, "customGroups" : [ "Pronghorn DSManager", "Pronghorn Developer", "Pronghorn DSOperator", "Pronghorn DSEngineer", "Pronghorn SystemAdmin" ], "tlsOptions": { "secureProtocol": "TLSv1_method", "requestCert": true, "rejectUnauthorized": false, "ca": "/opt/pronghorn/current/custom/keys/root.cer" } }, "groups": [], "brokers": [ "aaa" ] },
Set-up the default admin groups in authentication props. You may add a list of LDAP groups whose members will be treated as IAP administrators. Use the new Adapter ID as
provenance
, and the LDAP group name as thegroup
."authenticationProps": { "description": "Authentication", "uniqueSession": false, "admins": [ { "provenance": "Prod LDAP", "group": "Pronghorn SystemAdmin" }, ] },
Reload IAP for the new properties to be utilized.
Active Directory Configuration Example
Use the following example for Active Directory configuration.
{
"id": "ldap",
"type": "LDAP",
"properties": {
"domain": "example.pronghorn.io",
"url": "ldaps://example.pronghorn.io:636",
"bindUsername": "itential",
"bindPassword": "<your_ldap_password>",
"baseDN": "dc=itential,dc=io",
"baseGroupDN": "ou=groups,dc=pronghorn,dc=io",
"baseUserDN": "ou=people,dc=pronghorn,dc=io",
"groupSearchFilter": "(objectCategory=Group)",
"userSearchFilter": "sAMAccountName",
"userMembershipAttribute": "memberOf",
"healthCheckInterval": 5000,
"timeout": 5000,
"connectTimeout": 5000,
"idleTimeout": 5000,
"timeLimit": 10,
"reconnect": true,
"activeDirectory": true,
"tlsOptions": {
"secureProtocol": "TLSv1_method",
"requestCert": true,
"rejectUnauthorized": true,
"ca": "/etc/ssl/keys/activedirectory_ca.pem"
},
"customGroups" : [
"Group1",
"Group2"
]
},
"brokers": [ "aaa" ]
}
Configuring OpenLDAP
Use the following to set-up OpenLDAP with adapter-ldap
for the Itential Automation Platform (IAP).
Note: For documentation purposes, the following steps were executed from a CentOS 7 install.
Install OpenLDAP
To install and configure OpenLDAP:
Install
openldap
.yum install -y openldap openldap-clients openldap-servers
Encrypt the password for the admin.
[root@localhost cn=config]# slappasswd New password: Re-enter new password: {SSHA}HPHUXuZhbtOs0CIRhnWjglbitrlWt0Lh
Edit the
olcDatabase\=\{2\}hdb.ldif
file.vi /etc/openldap/slapd.d/cn=config/olcDatabase\=\{2\}hdb.ldif
Modify the attributes. Remember to replace the value for
olcRootPW
with the encrypted value of your unique password provided by theslappasswd
command.olcSuffix: dc=pronghorn,dc=io olcRootDN: cn=admin,dc=pronghorn,dc=io olcRootPW: {SSHA}HPHUXuZhbtOs0CIRhnWjglbitrlWt0Lh
Edit the
olcDatabase={1}monitor.ldif
file.vi /etc/openldap/slapd.d/cn=config/olcDatabase={1}monitor.ldif
Modify the access entry by deleting the existing line and replacing it with the following command.
olcAccess: {0}to * by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external, cn=auth" read by dn.base="cn=admin,dc=pronghorn,dc=io" read by * none
Validate the configuration. The
checksum
errors on the two files modified in Step 3 and Step 5 are expected.[root@localhost vagrant]# slaptest -u 5a9d88af ldif_read_file: checksum error on "/etc/openldap/slapd.d/cn=config/olcDatabase={1}monitor.ldif" 5a9d88af ldif_read_file: checksum error on "/etc/openldap/slapd.d/cn=config/olcDatabase={2}hdb.ldif" config file testing succeeded
Copy the
DB_CONFIG
file for OpenLDAP.ls -l /var/lib/ldap/DB_CONFIG cp /usr/share/openldap-servers/DB_CONFIG.example /var/lib/ldap/DB_CONFIG chown -R ldap:ldap /var/lib/ldap/
Restart
openldap
.systemctl enable slapd service slapd restart
Add standard OpenLDAP schemas.
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/cosine.ldif ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/inetorgperson.ldif
Add the
memberof
OpenLDAP schema.Note: For any steps that create an LDIF file, you may need to break the commands down into smaller chunks as illustrated below.
cat << EOF > /etc/openldap/schema/memberof.ldif dn: cn=module,cn=config cn: module objectclass: olcModuleList objectclass: top olcmoduleload: memberof.la olcmodulepath: /usr/lib64/openldap EOF cat << EOF > /etc/openldap/schema/enable-memberof.ldif dn: olcOverlay={0}memberof,olcDatabase={2}hdb,cn=config objectClass: olcConfig objectClass: olcMemberOf objectClass: olcOverlayConfig objectClass: top olcOverlay: memberof EOF cat << EOF > /etc/openldap/schema/refint.ldif dn: cn=module,cn=config cn: module objectclass: olcModuleList objectclass: top olcmoduleload: refint.la olcmodulepath: /usr/lib64/openldap EOF cat << EOF > /etc/openldap/schema/enable-refint.ldif dn: olcOverlay={1}refint,olcDatabase={2}hdb,cn=config objectClass: olcConfig objectClass: olcOverlayConfig objectClass: olcRefintConfig objectClass: top olcOverlay: {1}refint olcRefintAttribute: memberof member manager owner EOF
Import the following schema files (in order).
ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/memberof.ldif ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/enable-memberof.ldif ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/refint.ldif ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/openldap/schema/enable-refint.ldif
Add the OpenLDAP schema to create users and group nodes. This is a custom LDIF to create users and group organizational units, and the default admin user.
- Replace the
userPassword
component of the Itential admin user with a value obtained by running theslappasswd
utility. - Once the
ldapadd
command is executed, you will be prompted for a password. Enter the OpenLDAP admin password created in Step 2.
cat << EOF > /etc/openldap/schema/pronghorn.ldif dn: dc=pronghorn,dc=io objectclass: domain dc: pronghorn dn: ou=users,dc=pronghorn,dc=io description: pronghorn users objectclass: organizationalUnit ou: users dn: ou=groups,dc=pronghorn,dc=io description: pronghorn groups objectclass: organizationalUnit ou: groups dn: uid=admin@pronghorn,ou=users,dc=pronghorn,dc=io uid: admin@pronghorn objectClass: inetOrgPerson cn: admin sn: admin mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ EOF
- Replace the
Import the schema.
ldapadd -c -x -W -D "cn=admin,dc=pronghorn,dc=io" -f /etc/openldap/schema/pronghorn.ldif Enter LDAP Password: adding new entry "dc=pronghorn,dc=io" adding new entry "ou=users,dc=pronghorn,dc=io" adding new entry "ou=groups,dc=pronghorn,dc=io" adding new entry "uid=admin@pronghorn,ou=users,dc=pronghorn,dc=io"
Use Apache Directory Studio to connect to the LDAP server.
Verify the connect and credentials are running as expected.
Create Groups and Users in OpenLDAP
- Each group object should be created as a
groupOfUniqueNames
with its common name (cn
) containing the name of the group. - If the group object is some other class (i.e.
groupOfNames
), thegroupSearchFilter
in the LDAP adapter properties must be aligned with the class (i.e.objectClass=groupOfNames
).
Use the sample LDIF files to creates users and groups.
Create the following groups in OpenLDAP.
Group Description global_admin
Multi-Tenant Administrator Group global_ops
Multi-Tenant Operations Group tenant1_admin
Tenant1
Administrator Grouptenant1_ops
Tenant1
Operations Grouptenant2_admin
Tenant2
Administrator Grouptenant2_ops
Tenant2
Operations GroupCreate the following users in OpenLDAP.
User First Name Last Name Email Groups global@admin
admin global nobody@itential.io
global_admin
global@ops
ops global nobody@itential.io
global_ops
tenant1@admin
admin tenant1
nobody@itential.io
tenant1_admin
tenant1@ops
ops tenant1
nobody@itential.io
tenant1_ops
tenant2@admin
admin tenant2
nobody@itential.io
tenant2_admin
tenant2@ops
ops tenant2
nobody@itential.io
tenant2_ops
Adjust the users, passwords, and groups in the sample files (if needed).
Create the
tenant-users.ldif
file.cat << EOF > /etc/openldap/schema/tenant-users.ldif dn: uid=admin@global,ou=users,dc=pronghorn,dc=io uid: admin@global objectClass: inetOrgPerson cn: admin sn: global mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ dn: uid=admin@tenant1,ou=users,dc=pronghorn,dc=io uid: admin@tenant1 objectClass: inetOrgPerson cn: admin sn: tenant1 mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ dn: uid=admin@tenant2,ou=users,dc=pronghorn,dc=io uid: admin@tenant2 objectClass: inetOrgPerson cn: admin sn: tenant2 mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ dn: uid=ops@global,ou=users,dc=pronghorn,dc=io uid: ops@global objectClass: inetOrgPerson cn: ops sn: global mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ dn: uid=ops@tenant1,ou=users,dc=pronghorn,dc=io uid: ops@tenant1 objectClass: inetOrgPerson cn: ops sn: tenant1 mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ dn: uid=ops@tenant2,ou=users,dc=pronghorn,dc=io uid: ops@tenant2 objectClass: inetOrgPerson cn: ops sn: tenant2 mail: nobody@pronghorn.io userPassword: {SSHA}qPe2L+D5288ikfEXttx0hLr8hQIunHo+ EOF
Import the
tenant-users.ldif
file.ldapadd -c -x -W -D "cn=admin,dc=pronghorn,dc=io" -f /etc/openldap/schema/tenant-users.ldif
Create the
tenant-groups.ldif
file.at << EOF > /etc/openldap/schema/tenant-groups.ldif dn: cn=pronghorn_admin,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: pronghorn_admin member: uid=admin@pronghorn,ou=users,dc=pronghorn,dc=io dn: cn=global_admin,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: global_admin member: uid=admin@global,ou=users,dc=pronghorn,dc=io dn: cn=global_ops,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: global_ops member: uid=ops@global,ou=users,dc=pronghorn,dc=io dn: cn=tenant1_admin,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: tenant1_admin member: uid=admin@tenant1,ou=users,dc=pronghorn,dc=io dn: cn=tenant1_ops,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: tenant1_ops member: uid=ops@tenant1,ou=users,dc=pronghorn,dc=io dn: cn=tenant2_admin,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: tenant2_admin member: uid=admin@tenant2,ou=users,dc=pronghorn,dc=io dn: cn=tenant2_ops,ou=groups,dc=pronghorn,dc=io objectClass: groupOfNames cn: tenant2_ops member: uid=ops@tenant2,ou=users,dc=pronghorn,dc=io EOF
Import the
tenant-groups.ldif
file.ldapadd -c -x -W -D "cn=admin,dc=pronghorn,dc=io" -f /etc/openldap/schema/tenant-groups.ldif
OpenLDAP Configuration Example
The following is an example for OpenLDAP configuration. The hostname
in the URL must match the common name of the LDAP server certificate.
{
"id": "ldap",
"type": "LDAP",
"properties": {
"domain": "uid={0},ou=users,dc=pronghorn,dc=io",
"url": "ldaps://example.pronghorn.io:636",
"bindUsername": "cn=admin,dc=pronghorn,dc=io",
"bindPassword": "<your_user_password>",
"baseDN": "dc=pronghorn,dc=io",
"baseGroupDN": "ou=groups,dc=pronghorn,dc=io",
"baseUserDN": "ou=users,dc=pronghorn,dc=io",
"groupSearchFilter": "(objectClass=groupOfNames)",
"userSearchFilter": "uid",
"userMembershipAttribute": "memberOf",
"healthCheckInterval": 5000,
"timeout": 5000,
"connectTimeout": 5000,
"idleTimeout": 5000,
"timeLimit": 10,
"reconnect": true,
"activeDirectory": false,
"tlsOptions": {
"secureProtocol": "TLSv1_method",
"requestCert": true,
"rejectUnauthorized": true,
"ca": "/etc/ssl/keys/openldap_ca.pem"
} },
"brokers": [ "aaa" ]
}
Configuration to Authenticate LDAP Service
Once the LDAP server is running and populated with users and groups, configure the LDAP adapter to authenticate against the LDAP service.
Encrypt the
bindPassword
for the LDAP server using the IAP encryption tool.cd /opt/pronghorn/current npm run encrypt <your_password>
Verify the LDAP adapter section is present in the
properties.json
file. Sample configurations for both Active Directory and Open LDAP can be found in thedocumentation.md
file of the LDAP adapter./opt/itential/current/node_modules/@itential/adapter-ldap/docs/DOCUMENTATION.md
Example for LDAP Configuration
"adapterProps": { "adapters": [ { "id": "LDAP Server", "type": "LDAP", "properties": { "domain": "uid={0},ou=users,dc=pronghorn,dc=io", "url": "ldap://127.0.0.1:389", "bindUsername": "cn=admin,dc=pronghorn,dc=io", "bindPassword": "<ENTER ENCRYPTED PWD HERE>", "baseDN": "dc=pronghorn,dc=io", "groupSearchFilter": "(objectClass=groupOfNames)", "userSearchFilter": "uid", "healthCheckInterval": 5000, "timeout": 5000, "connectTimeout": 5000, "idleTimeout": 5000, "timeLimit": 10, "reconnect": true, "tlsOptions": { "secureProtocol": "TLSv1_method", "requestCert": false, "rejectUnauthorized": true, "ca": "keys/key.pem" }, "customGroups": [] } }, ... } ...
Example for OpenLDAP Configuration
"adapters": [ { "id": "LDAP Server", "type": "LDAP", "properties": { "domain": "uid={0},ou=users,dc=pronghorn,dc=io", "url": "ldap://127.0.0.1:389", "bindUsername": "cn=admin,dc=pronghorn,dc=io", "bindPassword": "<ENTER ENCRYPTED PWD HERE>", "baseDN": "dc=pronghorn,dc=io", "groupSearchFilter": "(objectClass=groupOfNames)", "userSearchFilter": "uid", "userMembershipAttribute": "memberOf", "healthCheckInterval": 5000, "timeout": 5000, "connectTimeout": 5000, "idleTimeout": 5000, "timeLimit": 10, "reconnect": true, "activeDirectory": false, "tlsOptions": { "secureProtocol": "TLSv1_method", "requestCert": false, "rejectUnauthorized": false, "ca": "keys/key.pem" } }, "groups": [], "brokers": [ "aaa" ] }, ...
Verify the LDAP adapter is registered as the AAA broker.
LDAP
"brokerProps": { "aaa": [ "LDAP Server" ], ... }
OpenLDAP
"groups": [], "brokers": [ "aaa" ] } ,
Verify the LDAP adapter is registered in provenance for 2018+.
"authenticationProps": { "admins": [ { "provenance": "LDAP Server", "group": "pronghorn_admin" } ], "description": "Authentication", "uniqueSession": false },
Restart IAP and verify user can login as the
admin@pronghorn
user.service pronghorn restart
Associate User Groups to Applications
After setting up the LDAP Adapter, you must associate your user groups with each IAP application and determine the roles they will have. This is done through the Groups section in Authorization Manager (Settings > Authorization > Groups).
Verify LDAP Connection
- Login to the LDAP server using your login.
- Open the IAP System view (Settings > System).
- Go to Adapters to confirm the connection to the LDAP server.
Troubleshooting
- Run the command
journalctl -fu pronghorn
. This command will display all output to the STDOUT. - Try to login to IAP using the browser and all errors will be displayed.